home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3s / fopen.z / fopen
Encoding:
Text File  |  2002-10-03  |  8.6 KB  |  198 lines
  1.  
  2.  
  3.  
  4. FFFFOOOOPPPPEEEENNNN((((3333SSSS))))                                                            FFFFOOOOPPPPEEEENNNN((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      fopen, freopen, fdopen - open a stream
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttddddiiiioooo....hhhh>>>>
  13.  
  14.      FFFFIIIILLLLEEEE ****ffffooooppppeeeennnn ((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffiiiilllleeeennnnaaaammmmeeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ttttyyyyppppeeee))));;;;
  15.  
  16.      FFFFIIIILLLLEEEE ****ffffrrrreeeeooooppppeeeennnn ((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffiiiilllleeeennnnaaaammmmeeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ttttyyyyppppeeee,,,, FFFFIIIILLLLEEEE ****ssssttttrrrreeeeaaaammmm))));;;;
  17.  
  18.      FFFFIIIILLLLEEEE ****ffffddddooooppppeeeennnn ((((iiiinnnntttt ffffiiiillllddddeeeessss,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ttttyyyyppppeeee))));;;;
  19.  
  20. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  21.      _f_o_p_e_n opens the file named by _f_i_l_e_n_a_m_e and associates a _s_t_r_e_a_m with it.
  22.      _f_o_p_e_n returns a pointer to the FILE structure associated with the _s_t_r_e_a_m.
  23.  
  24.      _f_i_l_e_n_a_m_e points to a character string that contains the name of the file
  25.      to be opened.
  26.  
  27.      _t_y_p_e is a character string.  The initial portion of _t_y_p_e must consist of
  28.      one of the following character sequences:
  29.  
  30.           rrrr _o_r rrrrbbbb        open for reading
  31.  
  32.           wwww _o_r wwwwbbbb        truncate or create for writing
  33.  
  34.           aaaa _o_r aaaabbbb        append: open for writing at end of file or create for
  35.                          writing
  36.  
  37.           rrrr++++,rrrr++++bbbb _o_r rrrrbbbb++++  open for update (reading and writing)
  38.  
  39.           wwww++++,wwww++++bbbb _o_r wwwwbbbb++++  truncate or create for update
  40.  
  41.           aaaa++++,aaaa++++bbbb _o_r aaaabbbb++++  append: open for update at end-of-file or create for
  42.                          update
  43.      As this implementation does not distinguish between _b_i_n_a_r_y and _t_e_x_t
  44.      files, the character bbbb in the string _t_y_p_e, (which is used to indicate
  45.      that the file being opened is a _b_i_n_a_r_y file) is inconsequential.
  46.  
  47.      Opening a file for reading (when rrrr is the first character of _t_y_p_e) will
  48.      fail if the file does not exist or is unreadable.
  49.  
  50.      When a file is opened for update (when ++++ appears as the second (or third,
  51.      in the case of _f_o_p_e_n or _f_r_e_o_p_e_n) character of _t_y_p_e) both input and output
  52.      may be done on the resulting _s_t_r_e_a_m.  However, output may not be directly
  53.      followed by input without an intervening _f_s_e_e_k, _f_s_e_t_p_o_s, or _r_e_w_i_n_d.
  54.      Similarly, input may not be directly followed by output without an
  55.      intervening call to one of these functions, unless the input operation
  56.      left the file positioned at end-of-file.  (See note under BUGS below.)
  57.  
  58.  
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. FFFFOOOOPPPPEEEENNNN((((3333SSSS))))                                                            FFFFOOOOPPPPEEEENNNN((((3333SSSS))))
  70.  
  71.  
  72.  
  73.      When a file is opened for append (i.e., when _t_y_p_e is aaaa, aaaabbbb, aaaa++++bbbb, aaaabbbb++++ or
  74.      aaaa++++), it is impossible to overwrite information already in the file.
  75.      _f_s_e_e_k may be used to reposition the file pointer to any position in the
  76.      file, but when output is written to the file, the current file pointer is
  77.      disregarded.  All output is written at the end of the file and causes the
  78.      file pointer to be repositioned at the end of the output.  If two
  79.      separate processes open the same file for append, each process may write
  80.      freely to the file without fear of destroying output being written by the
  81.      other.  The output from the two processes will be intermixed in the file
  82.      in the order in which it is written.
  83.  
  84.      _f_r_e_o_p_e_n substitutes the named file in place of the open _s_t_r_e_a_m.  An
  85.      attempt is made to close the original _s_t_r_e_a_m, using _f_c_l_o_s_e(3s).  If this
  86.      close attempt is unsuccessful, the failure is ignored. _f_r_e_o_p_e_n then
  87.      attempts to open the file indicated by _f_i_l_e_n_a_m_e, returning the result.
  88.      The character string _t_y_p_e must have the same form as for _f_o_p_e_n.  If the
  89.      open is successful, the end-of-file and error indicators for _s_t_r_e_a_m are
  90.      cleared.
  91.  
  92.      _f_r_e_o_p_e_n is typically used to attach the preopened _s_t_r_e_a_m_s associated with
  93.      ssssttttddddiiiinnnn, ssssttttddddoooouuuutttt and ssssttttddddeeeerrrrrrrr to other files.
  94.  
  95.      _f_d_o_p_e_n associates a stream with a file descriptor.  File descriptors are
  96.      obtained from _o_p_e_n, _d_u_p, _c_r_e_a_t, or _p_i_p_e(2), which open files but do not
  97.      initialize a stream, which is the object manipulated by many of the
  98.      Section 3S library routines.  _f_d_o_p_e_n initializes a stream for the open
  99.      file descriptor _f_i_l_d_e_s, and returns a pointer to the corresponding FILE
  100.      structure.  The character string _t_y_p_e has the same form as that for
  101.      _f_o_p_e_n, with the exception that the (superfluous) binary file
  102.      specification character bbbb, is not allowed.  (This restricts the initial
  103.      portion of _t_y_p_e to one of rrrr, wwww, aaaa, rrrr++++, wwww++++, or aaaa++++.)  The _t_y_p_e specified
  104.      for the stream must agree with the mode of the open file indicated by
  105.      _f_i_l_d_e_s (see _o_p_e_n(2)).
  106.  
  107. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  108.      creat(2), close(2), dup(2), open(2), pipe(2), write(2), fclose(3S),
  109.      fseek(3S), setbuf(3s), stdio(3S).
  110.  
  111. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  112.      _f_o_p_e_n, _f_d_o_p_e_n, and _f_r_e_o_p_e_n return a NULL pointer on failure.
  113.  
  114.      Depending on which ABI a program is compiled in, there may be a limit on
  115.      the number of open _s_t_d_i_o streams, or a limit on which file descriptors
  116.      may be associated with _s_t_d_i_o streams.  When compiling in nnnn33332222 or nnnn66664444
  117.      modes, there are no limits, however in oooo33332222 mode the functions _f_o_p_e_n or
  118.      _f_d_o_p_e_n may fail and not set _e_r_r_n_o if there are no free _s_t_d_i_o streams. No
  119.      more than 255 files may be opened via _f_o_p_e_n, and only file descriptors 0
  120.      through 255 are valid with _s_t_d_i_o streams.
  121.  
  122.      In oooo33332222 mode file descriptors used by _f_d_o_p_e_n must be less than 255.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                                                                         PPPPaaaaggggeeee 2222
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135. FFFFOOOOPPPPEEEENNNN((((3333SSSS))))                                                            FFFFOOOOPPPPEEEENNNN((((3333SSSS))))
  136.  
  137.  
  138.  
  139. BBBBUUUUGGGGSSSS
  140.      When operating on a file opened for update on which the last operation
  141.      was output, an input operation may be performed if there is an
  142.      intervening call to a file positioning function.  An input operation
  143.      should also be possible under these circumstances if an intervening call
  144.      is made to _f_f_l_u_s_h.  If this sequence of operations (i.e., output, _f_f_l_u_s_h,
  145.      input) is performed, however, the input operation fails with the
  146.      misleading error EEEEBBBBAAAADDDDFFFF.
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                                                         PPPPaaaaggggeeee 3333
  195.  
  196.  
  197.  
  198.